feat(SnapshotKit): support measured Duo capture geometry - #377

Posted by an AI agent on kve's behalf.

Summary

Add explicit frame layout traits and recorded Duo profiles to the Xcode 27.2 baseline from main. Apply requested content clearance after UIKit finalizes containment and native geometry.

This layer retains the existing Where navigation. Its image references establish the new capture baseline before the adaptive app changes. Calendar month sections, day rows, and Timeline rows measure eagerly so full-content captures include the final rows; the selection and tabletop changes remain in the app PR. Eager Timeline measurement removes blank tails caused by lazy height estimates in a bottom-anchored scroll view. Settings waits for native search chrome to settle before measuring its full height. Existing scrolling onboarding and Devices fixtures use full-content frames. Theme choices also fall back to a vertical layout when narrow, and large-text Logged Days rows retain their dates, notes, and labels.

Screenshots

Developer Overlay, light iPhone full-content capture. Retaining the scene restores uniform native glass without changing the menu's styling, dimensions, or content.

Before	After

Before: 9e759fc8. After: f05ca6240; all six overlay captures reproduced byte for byte.

Primary APIs

• SnapshotConfiguration.Frame.LayoutTraits owns horizontal and vertical size classes and interface idiom. Configuration-level layout traits remain supported and take precedence over frame defaults. Phone and iPad presets carry truthful traits without changing their filenames.
• Frame.scenePolicy controls capture scene retention without renaming references. Both configured assertions and hosted PNG export honor it.
• Frame.viewport captures bounded shell composition. It must be paired with full-content captures of scrolling panes.
• The four Duo profiles use measured native geometry. The module README retains the measurement date, runtime/build, collection method, and validation limits; the unused raw JSON dump is removed. .narrowWindow covers a synthetic multitasking container.

let configuration = SnapshotConfiguration(device: .duoInnerPortrait)
configuration.applyTraits(to: host)

Previews and UIKit capture use the same mapping. Conversion from configuration traits to frame traits uses exhaustive switches for both size classes and idiom, so new enum cases require an explicit mapping. Custom frames can supply layoutTraits; component frames inherit the host's traits.

Capture and tooling boundaries

All capture entry points acquire one lock before host discovery, validation, and preparation. Fixed, regular-width phone captures retain their scene so native bar geometry stays stable. Other synthetic captures detach the marked window by default, preserving compact title space and anchoring full-content search to expanded content. Capture and measurement hosts reconcile their effective insets after containment and layout, with another reconciliation after settling. The predicate uses content-controller traits, not pixel width or simulator identity. Frames can explicitly retain the scene when native chrome requires it. Periscope and Developer Overlay use this option without changing their configured traits, insets, or sizing. Developer Overlay's native glass otherwise develops bright bands and a hard material cutoff. Retention can expose physical reserved regions, so general presets keep the automatic policy. Both paths restore scene and presentation state on success or failure. A nil inset override retains native geometry.

Only the captured root overrides its safe-area getter, during final pixel rendering. Native getters remain active during containment, measurement, and settling so inset changes propagate to children. Root pinning protects translated tiles. Overriding ancestors doubled asymmetric insets after measurement rehosting. Annotation padding has zero safe-area insets to avoid moving centered content. Tall tiled Year annotations retain the pre-existing limitation listed below. Regressions cover these boundaries, already-mounted inputs, compact and regular title readability, native bar stability, tiling, and failure cleanup. Full-content captures reset restored scroll offsets after readiness; viewport captures preserve them.

Accessibility subjects stay mounted during readiness and settling. Ordinary captures retain their controller parent during parsing; only upstream tiling temporarily detaches it. Annotation wrappers grow only after the final accessibility parse. Synthetic viewports recover native navigation-bar metadata synchronously, restore window geometry before parsing, and restore the original getters on every exit.

Pixel settling retains main’s normalized pixel comparison and retry policy. Final reference-comparison tolerances remain unchanged. Hosted resize, restoration, full-content, PNG export, and cancellation checks cover the shared pipeline.

Snapshot shard discovery accepts literal multiline source arrays with shared support files. Unsupported declarations fail without borrowing a following target's sources. The existing shard assignments stay unchanged.

Compatibility and review focus

• The stack requires iOS 27.1. Development and CI use Xcode and simulator 27.2. The native macOS deployment target is unchanged.
• Review the capture isolation and frame-trait API changes before the references. The fix addresses stale inset compensation: requested top/bottom values of 5/9 previously reached native children as 0/0.
• The app integration in feat(WhereUI): adapt Where for iPhone Duo #372 fixes a separate stale developer-overlay inset delivery. Native accessibility capture corrections belong to this foundation layer; later app layers own their navigation and search behavior.
• The Duo profiles retain their recorded 27.1 measurements. Re-measurement on the native 27.2 Duo runtime remains an explicit release-validation item.
• Theme descriptions retain three lines of minimum space and grow for large text. The shared picker no longer truncates the Flat description at AX5.

Testing

• At 42ab5b40e, ./test --review --only SnapshotKitTests --only WhereUISnapshotTests/DeveloperOverlaySnapshotTests passed all 56 SnapshotKit tests and the Developer Overlay image suite (all six captures matched byte for byte). Architecture and SwiftFormat passed. Review fixes preserve the existing mappings and presets; no references changed.

• Full gates on the current head 42ab5b40e: GitHub Actions and CircleCI pipeline 2195.

• At f05ca6240, the full run passed 2,922 iOS unit tests and 28 host macro tests. All 71 snapshot tests are covered by the full run plus focused assertions after review; 679 affected WhereUI tests also passed after the eager Timeline change.

• ./test --no-generate --review --timings --only WhereUITests with the seven affected snapshot suites verified the refreshed references. A final ./test --no-generate --no-build --review --only WhereUISnapshotTests/DeveloperOverlaySnapshotTests repeated all six overlay captures byte for byte. Architecture checks and SwiftFormat passed.

• Full gates for the capture-repair baseline (before the exhaustive-conversion refactor and documentation cleanup): GitHub Actions and CircleCI pipeline 2188.

The capture fixes and reference migration are verified at this PR's own layer. A green stack tip cannot establish that an earlier PR's renderer and references agree. Layer-specific Timeline, Settings, and Year references retain the behavior present here rather than borrowing later adaptive UI semantics.

• Independent source review covered capture containment, final annotation sizing, native-bar getter restoration, Settings measurement, and eager Timeline layout. Visual review covered the refreshed references and preserved comparison-sheet metadata; comparison tolerances are unchanged.
• Two tall Year accessibility images retain a pre-existing marker offset and incomplete native-toolbar legends (STU-325).
• Native Duo 27.2 geometry re-measurement and interactive device checks remain pending. Synthetic regular-simulator coverage does not establish native system-bar geometry or spoken VoiceOver behavior.

Stack

First active layer, based on main after #376 merged. This supplies the capture foundation for #378 and #372. Capture corrections and their references land here; adaptive corrections and references land with the app integration.

Backlog reconciliation

The 13 preserved Duo records are tracked in Linear. STU-318 owns adoption and its six implementation sub-issues. This slice relates to STU-319, STU-320, STU-327. Unmerged implementation remains In Review.

Remaining Backlog work: native Duo release validation (STU-316), intermittent Locations settling diagnostics (STU-317), and tall Year accessibility annotations (STU-325). Existing STU-114 and STU-252 now distinguish the partial fixes from their remaining requirements; both retain their priorities, labels, and open state.